<?php
/**
 * class OpenDc311
 * PHP Wrapper class around the DC Open 311 API. This REQUIRES use of the sunlight-php PHP Wrapper class available from http://emmense.com
 * Docs for the DC Open 311 API are at http://api.dc.gov/open311/v1
 * @author Aaron Brazell <aaron@technosailor.com>
 * @version 1.1-beta
 * @package sunlight-php
 */
class OpenDc311 extends SunlightData {
	
	/**
	 * Version number of the Open 311 API. Defaults to v1
	 * @var $type
	 **/
	var $api_version = 'v1';
	
	/**
	 * A method for submitting new 311 service requests. 
	 * @param array $service_request_data required. An array of fields necessary for creating a 311 request
	 * @return object
	 * @todo verify data. There is no set of arguments with which to test with yet
	 **/
	function createServiceRequest( $service_request_data = array() )
	{
		$endpoint = $this->request_url . $this->api_version . '/submit.' . $this->type;
		$data = $this->_request( $endpoint, $service_request_data );
	}
	
	/**
	 * A method for retrieving service requests via token. 
	 * @param string $token required. A unique token needed to retrieve the ID number of a service request
	 * @return int
	 **/
	function getServiceRequestID( $token )
	{
		$endpoint = $this->request_url . $this->api_version . '/getFromToken.' . $this->type;
		$qs = $this->_glue( array( 'token' => $token ) );
		$data = $this->_request( $endpoint . $qs );
		return (int) $data->servicerequestid;
	}
	
	/**
	 * A method for retrieving service requests via service request ID. 
	 * @param int $request_id required. A unique integer identifier for a service request
	 * @return object
	 **/	
	function getServiceRequest( $request_id )
	{
		$endpoint = $this->request_url . $this->api_version . '/get.' . $this->type;
		$qs = $this->_glue( array('servicerequestid' => (int) $request_id ) );
		$data = $this->_request( $endpoint . $qs );
		return (object) $data->servicerequest;
	}

	/**
	 * A method for retrieving a list of services provided by DC 311. 
	 * @return object
	 **/	
	function getServices()
	{
		$endpoint = $this->request_url . $this->api_version . '/meta_getTypesList.' . $this->type;
		$data = $this->_request( $endpoint );
		return (object) $data->servicetypeslist;
	}

	/**
	 * A method for retrieving information about a type of service provided by DC 311. 
	 * @param string $service_code required. A unique service identifier
	 * @return object
	 **/
	function getServicesMeta( $service_code )
	{
		$endpoint = $this->request_url . $this->api_version . '/meta_getTypeDefinition.' . $this->type;
		$qs = $this->_glue( array('servicecode' => $service_code ) );
		$data = $this->_request( $endpoint . $qs );
		return (object) $data->servicetypedefinition;
	}
}

/**
 * class OpenDc311Geocode
 * PHP Wrapper class around the DC Open 311 Geocoding API. This REQUIRES use of the sunlight-php PHP Wrapper class available from http://emmense.com
 * Docs for the DC Open 311 API are at http://api.dc.gov/geocoding/v1
 * @author Aaron Brazell <aaron@technosailor.com>
 * @version 1.1-beta
 * @package sunlight-php
 */
class OpenDc311Geocode extends SunlightData {

	/**
	 * Version number of the Open 311 API. Defaults to v1
	 * @var $type
	 **/	
	var $api_version = 'v1';

	/**
	 * A method for retrieving information about an address based on fuzzy search. 
	 * @param string $address required. Washington, DC street address, must have at least building number and street name
	 * @return object
	 **/	
	function getAddresses( $address )
	{
		$endpoint = $this->request_url . $this->api_version . '/search.' . $this->type;
		$qs = $this->_glue( array( 'address' => $address ) );
		$data = $this->_request( $endpoint . $qs );
		return (object) $data->addresses;
	}

	/**
	 * A method for retrieving information about an address based on latitude and longitude coordinates. 
	 * @param string $latitude required. Latitude coordinate
	 * @param string $longitude requires. Longitude coordinate
	 * @return object
	 **/	
	function getAddressByCoordinates( $latitude, $longitude )
	{
		$endpoint = $this->request_url . $this->api_version . '/getFromLatLong.' . $this->type;
		$qs = $this->_glue( array( 'lat' => $latitude, 'long' => $longitude ) );
		$data = $this->_request( $endpoint . $qs );
		return (object) $data->addresses;
	}
	
	/**
	 * A method for retrieving an information about an address based on the unique MAR ID. 
	 * @param integer $address_id required. This number can be obtained, if unknown, from $this->getAddresses() or $this->getAddressByCoordinates()
	 * @return object
	 **/
	function getAddressById( $address_id )
	{
		$endpoint = $this->request_url . $this->api_version . '/get.' . $this->type;
		$qs = $this->_glue( array( 'aid' => (int) $address_id ) );
		$data = $this->_request( $endpoint . $qs );
		return (object) $data->address;
	}
}
?>